Skip to content

Add async waitFor() helper for DOM-based detections#227

Open
Copilot wants to merge 5 commits intomainfrom
copilot/add-element-ready-helper
Open

Add async waitFor() helper for DOM-based detections#227
Copilot wants to merge 5 commits intomainfrom
copilot/add-element-ready-helper

Conversation

Copy link
Contributor

Copilot AI commented Jan 24, 2026 •
edited
Loading

DOM-based detections like isOrganizationProfile() can fail if called before elements render. This adds an async wrapper to poll detections until they return true or the document completes loading.

Implementation

  • utils.waitFor(detection): Polls detection function via requestAnimationFrame until it returns true or document.readyState === 'complete'
  • Returns final detection result as Promise<boolean>
  • Exported via utils object for better organization

Usage

import {utils, isOrganizationProfile} from 'github-url-detection';

async function init() {
  if (!await utils.waitFor(isOrganizationProfile)) {
    return;
  }
  // Element is now present or document is complete
}

Works with any detection function. Useful for features that initialize before page load completes.

Original prompt

This section details on the original issue you should resolve

<issue_title>Add elementReady-like helper for DOM detections</issue_title>
<issue_description>Sometimes we want to test whether a page matches before it's done downloading, this can be done by passing a selector to element-ready.

I have 2 ideas:

Static definitions

Instead of being just a function, we can define the detections as a list of constraints like:

- const canUserEditOrg = (url) => isOrganizationProfile() && exists('.pagehead-tabs-item[href$="/settings/profile"]')
+ const canUserEditOrgDefinition = [isOrganizationProfile, '.pagehead-tabs-item[href$="/settings/profile"]']
+ export canUserEditOrg = solveConstraints(canUserEditOrgDefinition);
+ export canUserEditOrgAsync = solveConstraintsAsync(canUserEditOrgDefinition);

But this gets wordy FAST

Duplicate functions

  const canUserEditOrg = (url) => isOrganizationProfile() && exists('.pagehead-tabs-item[href$="/settings/profile"]')
+ const canUserEditOrgAsync = async (url) => isOrganizationProfile() && await existsReady('.pagehead-tabs-item[href$="/settings/profile"]')

</issue_description>

Comments on the Issue (you are @copilot in this section)

@fregante ### Wrapper idea

ElementReady is nothing but a requestAnimationFrame-based loop that calls querySelector until found. This means we can offer a simple wrapper that does this with any detection:

import {wait, canEditSidebar} from '';

function init() {
  if(!await wait(canEditSidebar)) 
    return false
}
  • Pure DOM-based detections would be perfect this way;
  • Pure URL-based detections wouldn’t need it;
  • Mixed detections would unnecessarily test the URL every time, but probably we don’t have to worry about the “performance impact” of this

Alternatively the detections could internally replace exists with an async version, but it would be impossible to effectively handle multiple checks in the same detection:

await canEditSidebar({async: true})
```</body></comment_new>
<comment_new><author>@fregante</author><body>
Something like:
```js
export async function wait(detection) {
	while (!detection() && document isn't ready) {
		await Promise(requestAnimationFrame)
	}

	return detection();
}
```</body></comment_new>
<comment_new><author>@fregante</author><body>
Note that we moved these user-capability detections to the API in Refined GitHub:

- https://github.com/refined-github/refined-github/pull/7798

However there are still other DOM-based detection like `isOrganizationProfile` that would benefit from this</body></comment_new>
</comments>

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

Copilot AI and others added 2 commits January 24, 2026 10:10
@fregante
Add wait helper function for async detection
3c07716 
Implement the wait() async helper function that waits for a detection
to return true by repeatedly checking it on each animation frame. This
is useful for DOM-based detections that need to wait for elements to
appear before the document is fully loaded.

- Add wait() function that loops using requestAnimationFrame
- Add comprehensive tests for the wait function
- Update test infrastructure to support async detection functions
- Add JSDoc documentation with usage examples

Co-authored-by: fregante <1402241+fregante@users.noreply.github.com>
@fregante
Add wait helper documentation to README
95239d0 
Co-authored-by: fregante <1402241+fregante@users.noreply.github.com>
@fregante fregante marked this pull request as ready for review January 24, 2026 10:12
@fregante
Fix test cleanup in wait test to handle undefined descriptor
4efdd75 
Co-authored-by: fregante <1402241+fregante@users.noreply.github.com>
Copilot AI changed the title [WIP] Add elementReady-like helper for DOM detections Add async wait() helper for DOM-based detections Jan 24, 2026
Copilot AI requested a review from fregante January 24, 2026 10:17
fregante
fregante reviewed Jan 24, 2026
View reviewed changes
index.ts Outdated
* }
* ```
*/
export async function wait(detection: () => boolean): Promise<boolean> {
Copy link
Member

@fregante fregante Jan 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@copilot

  • Export via utils only.
  • Revert type changes (detectionFn = detect as) in index.test.ts
  • Rename to waitFor

Copy link
Contributor Author

Copilot AI Jan 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done in commit b177e73:

  • Renamed wait to waitFor
  • Moved to utils export only (removed direct export)
  • Reverted type assertion changes in index.test.ts

fregante
fregante approved these changes Jan 24, 2026
View reviewed changes
Copy link
Member

@fregante fregante left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hopefully this works well 😍

@fregante
Rename wait to waitFor and export via utils only
b177e73 
- Renamed wait() to waitFor() as requested
- Moved export to utils object instead of direct export
- Reverted type assertion changes in index.test.ts
- Updated README to show usage via utils.waitFor()
- Updated JSDoc example to reflect new API

Co-authored-by: fregante <1402241+fregante@users.noreply.github.com>
Copilot AI changed the title Add async wait() helper for DOM-based detections Add async waitFor() helper for DOM-based detections Jan 24, 2026
Copilot AI requested a review from fregante January 24, 2026 10:51
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@fregante fregante Awaiting requested review from fregante

Assignees

@fregante fregante

Copilot code review Copilot

Labels

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Add elementReady-like helper for DOM detections

2 participants

@fregante